Inside Macintosh: QuickTime /

Chapter 2 - Movie Toolbox / Movie Toolbox Reference

Functions for Editing Movies / Adding Samples to Media Structures

AddMediaSample

The AddMediaSample function adds sample data and a description to a media. Your application specifies the sample and the media for the operation. The AddMediaSample function updates the media so that it contains the sample data. One call to this function can add several samples to a media--however, all the samples must be the same size. Samples are always appended to the end of the media. Furthermore, each time a sample is added, the media duration is extended.

pascal OSErr AddMediaSample (Media theMedia, Handle dataIn, 
                     long inOffset, unsigned long size, 
                     TimeValue durationPerSample,
                     SampleDescriptionHandle sampleDescriptionH, 
                     long numberOfSamples, short sampleFlags, 
                     TimeValue *sampleTime); 

theMedia

Specifies the media for this operation. Your application obtains this media identifier from such Movie Toolbox functions as NewTrackMedia and GetTrackMedia (described on page 2-138 and page 2-190, respectively).

dataIn

Contains a handle to the sample data. The AddMediaSample function adds this data to the media specified by the parameter theMedia. You specify the number of bytes of sample data with the size parameter. You can use the inOffset parameter to specify a byte offset into the data referred to by this handle.

inOffset

Specifies an offset into the data referred to by the handle contained in the dataIn parameter. Set this parameter to 0 if there is no offset.

size

Specifies the number of bytes of sample data to be added to the media. This parameter indicates the total number of bytes in the sample data to be added to the media, not the number of bytes per sample. Use the numberOfSamples parameter to indicate the number of samples that are contained in the sample data.

durationPerSample

Specifies the duration of each sample to be added. You must specify this parameter in the media's time scale. For example, if you are adding sound that was sampled at 22 kHz to a media that contains a sound track with the same time scale, you would set the durationPerSample parameter to 1. Similarly, if you are adding video that was recorded at 10 frames per second to a video media that has a time scale of 600, you would set this parameter to 60 to add a single sample.

sampleDescriptionH

Contains a handle to a sample description. Some media structures may require sample descriptions. There are different sample descriptions for different types of samples. For example, a media that contains compressed video requires that you supply an image description (see the chapter "Image Compression Manager" in this book for more information about image description structures). A media that contains sound requires that you supply a sound description structure (see "The Sound Description Structure" on page 2-68 for more information about sound description structures).

If the media does not require a sample description, set this
parameter to nil.

numberOfSamples

Specifies the number of samples contained in the sample data to be added to the media.

This parameter determines the size of each sample. The Movie Toolbox considers the value of this parameter as well as the value of the size parameter when it determines the size of each sample that it adds to the media. You should set the value of this parameter so that the resulting sample size represents a reasonable compromise between total data retrieval time and the overhead associated with input and output (I/O). You should also consider the speed of the data storage device--CD-ROM devices are much slower than hard disks, for example, and should therefore have a smaller sample size.

For a video media, set a sample size that corresponds to the size of a frame. For a sound media, choose a number of samples that corresponds to between 0.5 and 1.0 seconds of sound. In general, you should not create groups of sound samples that are less than 2 KB in size or greater than 15 KB. Typically, a sample size of about 8 KB is reasonable for most storage devices.

sampleFlags

Contains flags that control the add operation. The following flag is available (set unused flags to 0):

mediaSampleNotSync

Indicates that the sample to be added is not a sync sample. Set this flag to 1 if the sample is not a sync sample. Set this flag to 0 if the sample is a sync sample.

sampleTime

Contains a pointer to a time value. After adding the sample data to the media, the AddMediaSample function returns the time where the sample was inserted in the time value referred to by this parameter. If you do not want to receive this information, set this parameter to nil.

DESCRIPTION

The AddMediaSample function updates the file or device that contains the movie data file as part of the add operation. Consequently, your application must have started a media-editing session before calling this function. You start a media-editing session with the BeginMediaEdits function, which is described on page 2-255. If you want to work with samples that have already been added to a movie data file, use the AddMediaSampleReference function, which is described in the next section.

ERROR CODES

invalidMedia

-2008

This media is corrupted or invalid

File Manager errors
Memory Manager errors